Skip to main content

Scheduling API Calls

You can use a scheduling tool to call an API at a regular date and time so routine transactions are started at the same time each day, week, month etc. Typically this would be done using Windows Task Scheduler, but any scheduling tool can be used.

tip

UniFi has an internal scheduler which in most cases is a more straightforward method of scheduling tasks. Its worth considering whether that is capable of meeting your requirements before attempting to use external scheduling tools.

Using Windows Powershell​

In order to create a transaction in UniFi you need to make a call to the 'save' API as described in the 'Available APIs' section of this help. However, this will only create a draft transaction. Often you will want to 'submit' the transaction as well so it can go on to the next step of the process. You therefore also need to make a call to the 'submit' API using the transaction ID that the was created when the transaction was first saved. Windows Powershell is a good way to create a script to do this and allows you to run that script to ensure it works correctly before adding it to the scheduled tasks.

Open Windows Powershell from the Windows start button. The first line of your script will look something like this:

$resp = Invoke-WebRequest -Method 'POST' -Uri "https://<client>.unifiplatform.com/api/EntryModule/Save?moduleId=<moduleId>" -Headers @{'accept' = '*/*'; 'x-api-key' = '<api_key>'; 'Content-Type' = 'application/json'}

  • $resp means a variable is created called $resp which holds the response to the API call

  • Invoke-WebRequest makes a call to a URL, in this case a UniFi API. This has a number of parameters

  • -Method is the method of the API call, usually 'POST'. See the section on available API's for the correct method to use for the call you are making.

  • -Uri is the Uniform Resource Indicator for the API you are calling, this will incorporate your unique client reference and module ID as described in the section on available API's. In this case we are using the EntryModule/Save endpoint to create a new transaction.

  • Headers contains the required headers for this API call, this will include the API key which authenticates the call.

tip

Default values set in the form designer will not automatically populate via an API call. To set values add a -Body to the above to incorporate the field IDs and values you wish to populate in JSON format. An example of this is given below.

This will create a draft transaction. If you want to submit that transaction on to the next step of the process you will also need to use the EntryModule/Submit endpoint. This will require the transaction ID of the transaction previously created, which is available in the JSON response to the earlier 'save' call. We can obtain this by first reading in to another variable using the 'ConvertFrom-Json' command. We can then read the JSON values using the syntax <variable>.<JSONfield> which can be in several heirarchical steps if necessary. We can then use this value to construct the URI for the 'submit' call. So the full script would be something like:

$resp = Invoke-WebRequest -Method 'POST' -Uri "https://mycompany.unifiplatform.com/api/EntryModule/Save?moduleId=<moduleId>" -Headers @{'accept' = 'text/plain'; 'x-api-key' = '<apikey>'; 'Content-Type' = 'application/json'} -Body '{"currencies_to_upload":"USD,EUR,GBP"}'
$json = ConvertFrom-Json $resp
$surl = "https://mycompany.unifiplatform.id/api/EntryModule/submit?moduleId=2d497cb6ea1a4a9bba13b4cba3e1ee89&recordId="+$json.data.Id
$submit = Invoke-WebRequest -Method 'POST' -Uri $surl -Headers @{'accept' = 'text/plain'; 'x-api-key' = '1952553d26204d4abd995b8abf5c10be'}

Note that in this example we are also using the -Body option in the first line to set the values for the 'currencies_to_upload' field ID.

Scheduling the script​

Once the Powershell script has been successfully tested you can use the Windows Task Scheduler to run it at a set frequency. You would normally do this by selecting the 'Start a program' action, the program being 'Powershell.exe' and the optional argument being the switch -file followed by the file location and name enclosed in double-quotes. You may also need to use the argument '-executionpolicy bypass' if security setting on the server you are using cause an issue with running the script from a scheduler. So a completed argument might look something like:

-executionpolicy bypass -file "C:\MyFolder\MyPowershellScript.ps1"

tip

Powershell uses Microsoft Internet Explorer in the background when invoking a webrequest. if the Internet Explorer has never been opened while logged in as the account running the scheduled tasks (this is quite likely if a system account is being used) then it will cause an issue. To get around this you need to log in to Windows as the account you want to run the scheduled tasks as, open Internet Explorer, set any one-time time browser preferences it asks about and then close again.